home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat2 / standard / getsockopt.z / getsockopt
Encoding:
Text File  |  1998-10-20  |  10.0 KB  |  199 lines
  1.  
  2.  
  3.  
  4. GGGGEEEETTTTSSSSOOOOCCCCKKKKOOOOPPPPTTTT((((2222))))                                                    GGGGEEEETTTTSSSSOOOOCCCCKKKKOOOOPPPPTTTT((((2222))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      getsockopt, setsockopt - get and set options on sockets
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ttttyyyyppppeeeessss....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ssssoooocccckkkkeeeetttt....hhhh>>>>
  14.  
  15.      iiiinnnntttt ggggeeeettttssssoooocccckkkkoooopppptttt((((iiiinnnntttt ssss,,,, iiiinnnntttt lllleeeevvvveeeellll,,,, iiiinnnntttt ooooppppttttnnnnaaaammmmeeee,,,, vvvvooooiiiidddd ****ooooppppttttvvvvaaaallll,,,,
  16.                iiiinnnntttt ****ooooppppttttlllleeeennnn))));;;;
  17.  
  18.      iiiinnnntttt sssseeeettttssssoooocccckkkkoooopppptttt((((iiiinnnntttt ssss,,,, iiiinnnntttt lllleeeevvvveeeellll,,,, iiiinnnntttt ooooppppttttnnnnaaaammmmeeee,,,, ccccoooonnnnsssstttt vvvvooooiiiidddd ****ooooppppttttvvvvaaaallll,,,,
  19.                iiiinnnntttt ooooppppttttlllleeeennnn))));;;;
  20.  
  21. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  22.      _G_e_t_s_o_c_k_o_p_t and _s_e_t_s_o_c_k_o_p_t manipulate _o_p_t_i_o_n_s associated with a socket.
  23.      Options may exist at multiple protocol levels; they are always present at
  24.      the uppermost ``socket'' level.
  25.  
  26.      When manipulating socket options the level at which the option resides
  27.      and the name of the option must be specified.  To manipulate options at
  28.      the ``socket'' level, _l_e_v_e_l is specified as SOL_SOCKET.  To manipulate
  29.      options at any other level the protocol number of the appropriate
  30.      protocol controlling the option is supplied.  For example, to indicate
  31.      that an option is to be interpreted by the TCP protocol, _l_e_v_e_l should be
  32.      set to the protocol number of TCP; see _g_e_t_p_r_o_t_o_e_n_t(3N).
  33.  
  34.      The parameters _o_p_t_v_a_l and _o_p_t_l_e_n are used to access option values for
  35.      _s_e_t_s_o_c_k_o_p_t.  For _g_e_t_s_o_c_k_o_p_t they identify a buffer in which the value for
  36.      the requested option(s) are to be returned.  For _g_e_t_s_o_c_k_o_p_t, _o_p_t_l_e_n is a
  37.      value-result parameter, initially containing the size in bytes of the
  38.      buffer pointed to by _o_p_t_v_a_l, and modified on return to indicate the
  39.      actual size of the value returned.  If the size of the option value is
  40.      greater than the value of _o_p_t_l_e_n, then the option will be truncated
  41.      silently to _o_p_t_l_e_n bytes.
  42.  
  43.      If no option value is to be supplied or returned, _o_p_t_v_a_l may be supplied
  44.      as 0.
  45.  
  46.      _O_p_t_n_a_m_e and any specified options are passed uninterpreted to the
  47.      appropriate protocol module for interpretation.  The include file
  48.      <_s_y_s/_s_o_c_k_e_t._h> contains definitions for ``socket'' level options,
  49.      described below.  Options at other protocol levels vary in format and
  50.      name; consult the appropriate entries in section (7P).
  51.  
  52.      Most socket-level options listed in the table below take an _i_n_t parameter
  53.      for _o_p_t_v_a_l.  For _s_e_t_s_o_c_k_o_p_t, the parameter should non-zero to enable a
  54.      boolean option, or zero if the option is to be disabled.  SO_LINGER uses
  55.      a _s_t_r_u_c_t _l_i_n_g_e_r parameter, defined in <_s_y_s/_s_o_c_k_e_t._h>, which specifies the
  56.      desired state of the option and the linger interval (see below).
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GGGGEEEETTTTSSSSOOOOCCCCKKKKOOOOPPPPTTTT((((2222))))                                                    GGGGEEEETTTTSSSSOOOOCCCCKKKKOOOOPPPPTTTT((((2222))))
  71.  
  72.  
  73.  
  74.      The following options are recognized at the socket level.  Except as
  75.      noted, each may be examined with _g_e_t_s_o_c_k_o_p_t and set with _s_e_t_s_o_c_k_o_p_t.
  76.  
  77.  
  78.      SO_DEBUG       toggle recording of debugging information
  79.      SO_REUSEADDR   toggle local address reuse
  80.      SO_KEEPALIVE   toggle keep connections alive
  81.      SO_DONTROUTE   toggle routing bypass for outgoing messages
  82.      SO_LINGER      linger on close if data present
  83.      SO_BROADCAST   toggle permission to transmit broadcast messages
  84.      SO_OOBINLINE   toggle reception of out-of-band data in band
  85.      SO_REUSEPORT   toggle local port reuse for multicast programs
  86.      SO_SNDBUF      set buffer size for output
  87.      SO_RCVBUF      set buffer size for input
  88.      SO_TYPE        get the type of the socket (get only)
  89.      SO_ERROR       get and clear error on the socket (get only)
  90.  
  91.  
  92.      SO_DEBUG enables debugging in the underlying protocol modules.
  93.      SO_REUSEADDR indicates that the rules used in validating addresses
  94.      supplied in a _b_i_n_d(2) call should allow reuse of local addresses.
  95.      SO_REUSEPORT indicates that the rules used in validating ports supplied
  96.      in a _b_i_n_d(2) call should allow reuse of local ports. It allows multiple
  97.      programs to receive UDP multicast/broadcast datagrams on the same port if
  98.      they all set SO_REUSEPORT before binding the port.  SO_KEEPALIVE enables
  99.      the periodic transmission of messages on a connected socket.  Should the
  100.      connected party fail to respond to these messages, the connection is
  101.      considered broken and processes using the socket are notified via a
  102.      SIGPIPE signal.  SO_DONTROUTE indicates that outgoing messages should
  103.      bypass the standard routing facilities.  Instead, messages are directed
  104.      to the appropriate network interface according to the network portion of
  105.      the destination address.
  106.  
  107.      SO_LINGER controls the action taken when unsent messages are queued on
  108.      socket and a _c_l_o_s_e(2) is performed.  If the socket promises reliable
  109.      delivery of data and SO_LINGER is set, the system will block the process
  110.      on the _c_l_o_s_e attempt until it is able to transmit the data or until it
  111.      decides it is unable to deliver the information (a timeout period, termed
  112.      the linger interval, is specified in the _s_e_t_s_o_c_k_o_p_t call when SO_LINGER
  113.      is requested). If SO_LINGER is disabled and a _c_l_o_s_e is issued, the system
  114.      will process the close in a manner that allows the process to continue as
  115.      quickly as possible.
  116.  
  117.      The option SO_BROADCAST requests permission to send broadcast datagrams
  118.      on the socket.  Broadcast was a privileged operation in earlier versions
  119.      of the system.  With protocols that support out-of-band data, the
  120.      SO_OOBINLINE option requests that out-of-band data be placed in the
  121.      normal data input queue as received; it will then be accessible with _r_e_c_v
  122.      or _r_e_a_d calls without the MSG_OOB flag.  SO_SNDBUF and SO_RCVBUF are
  123.      options to adjust the normal buffer sizes allocated for output and input
  124.      buffers, respectively.  The buffer size may be increased for high-volume
  125.      connections, or may be decreased to limit the possible backlog of
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GGGGEEEETTTTSSSSOOOOCCCCKKKKOOOOPPPPTTTT((((2222))))                                                    GGGGEEEETTTTSSSSOOOOCCCCKKKKOOOOPPPPTTTT((((2222))))
  137.  
  138.  
  139.  
  140.      incoming data.  The system places an absolute limit on these values.
  141.      Finally, SO_TYPE and SO_ERROR are options used only with _g_e_t_s_o_c_k_o_p_t.
  142.  
  143.      SO_TYPE returns the type of the socket, such as SOCK_STREAM; it is useful
  144.      for servers that inherit sockets on startup.  SO_ERROR returns any
  145.      pending error status on the socket and clears the error status. It may be
  146.      used to check for asynchronous errors on connected datagram sockets or
  147.      for other asynchronous errors.  The error status is an _e_r_r_n_o value as
  148.      described in _i_n_t_r_o(2).
  149.  
  150. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  151.      A 0 is returned if the call succeeds, -1 if it fails.
  152.  
  153. EEEERRRRRRRROOOORRRRSSSS
  154.      The call succeeds unless:
  155.  
  156.      [EBADF]             The argument _s is not a valid descriptor.
  157.  
  158.      [ENOTSOCK]          The argument _s is a file, not a socket.
  159.  
  160.      [ENOPROTOOPT]       The option is unknown at the level indicated.
  161.  
  162.      [EFAULT]            The address pointed to by _o_p_t_v_a_l is not in a valid
  163.                          part of the process address space.  For _g_e_t_s_o_c_k_o_p_t,
  164.                          this error may also be returned if _o_p_t_l_e_n is not in a
  165.                          valid part of the process address space.
  166.  
  167.      [EINVAL]            The option length is too small. Most socket-level
  168.                          options expect _o_p_t_l_e_n to be _s_i_z_e_o_f(_i_n_t).
  169.  
  170. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  171.      ioctl(2), socket(2), getprotoent(3N), ip(7P), tcp(7P), udp(7P)
  172.  
  173. NNNNOOOOTTTTEEEE
  174.      ABI-compliant versions of the above calls can be obtained from
  175.      _l_i_b_s_o_c_k_e_t._s_o.
  176.  
  177. BBBBUUUUGGGGSSSS
  178.      Several of the socket options should be handled at lower levels of the
  179.      system.
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.